Document format function #1374

rsill-neo4j · 2025-08-29T07:52:04Z

No description provided.

…acters tables, added more headings

JoelBergstrand

Great work! I'd like an update to the toString page, or where you think it would be relevant, that temporal values by default output on the ISO format. It should be clear to the user that you don't need to use the format function to get ISO.

JoelBergstrand · 2025-09-04T11:16:14Z

modules/ROOT/pages/functions/temporal/format.adoc

+----
+WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
+RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| x
+| "1986-11-18T06:04:45.123+0100"
+1+d|Rows: 1


I don't think we should lead with this test as it return the ISO representation of the datetime, e.g. it doesn't do anything new and useful.

JoelBergstrand · 2025-09-04T11:18:39Z

modules/ROOT/pages/functions/temporal/format.adoc

+If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present, for example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern.
+This is because without a reference point, there is no way of determining the specifics of a duration.
+
+For example, not all months have the same number of days, and switches to or from daylight saving time means that a day has 23 or 25 hours rather than 24.


I wonder if this should be omitted as we discuss this in components of durations

only line 262, or the entire introduction?

Line 262 is my thinking, the reset it format specfic information

JoelBergstrand · 2025-09-04T11:19:35Z

modules/ROOT/pages/functions/temporal/format.adoc

+
+
+[[query-functions-temporal-format-duration-types-characters]]
+=== String pattern characters


Looks like there might be a line too much after this title

the spacing in the preview?

i think this might be because of table title 🤔 it's correct in the source document (or rather, i'm pretty sure it wouldn't make a difference in this case)

JoelBergstrand · 2025-09-04T11:22:24Z

modules/ROOT/pages/functions/temporal/format.adoc

+[[query-functions-temporal-format-duration-types-examples]]
+=== Examples
+
+.Duration formatting, years converted to quarters


For all these test we use the full duration constructor, even when test don't use all component groups. As the map is big and ugly, do we want it in all tests? Or a smaller map with only relevant values?

JoelBergstrand · 2025-09-04T11:23:19Z

modules/ROOT/pages/values-and-types/temporal.adoc

+.Query
+[source, cypher, indent=0]
+----
+WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
+RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| x
+| "1986-11-18T06:04:45.123+0100"
+1+d|Rows: 1


I'd switch this to the EU -> US example.

gem-neo4j · 2025-09-08T09:12:28Z

modules/ROOT/pages/functions/temporal/format.adoc

+
+The format function creates dynamically formatted string representations of temporal instance and duration types.
+The output format can be customized via the `pattern` parameter.
+Creating a pattern follows the rules for the link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter].


This links to Java 8, but we use 21:
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html

gem-neo4j · 2025-09-08T09:13:43Z

modules/ROOT/pages/functions/temporal/format.adoc

+.Details
+|===
+| *Syntax*         3+| `format(value[, pattern])`
+| *Description*    3+| Returns the temporal value as an ISO-formatted string or as a string formatted by the provided pattern.


Don't we normally say STRING etc in these descriptions?

gem-neo4j · 2025-09-08T09:15:22Z

modules/ROOT/pages/functions/temporal/format.adoc

+|===
+| Most characters yield a different output when they are repeated.
+| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value.
+| For details, refer to the documentation of the link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter].


Same as above: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html

modules/ROOT/pages/functions/temporal/format.adoc

Co-authored-by: Gem Lamont <[email protected]>

JPryce-Aklundh

Looks good! My main suggestion would be to put the Considerations table immediately after the Details table (as with the other functions), and to put most of the details from your introductory paragraph in the Considerations table.

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

modules/ROOT/pages/functions/temporal/format.adoc

JPryce-Aklundh · 2025-09-10T07:52:35Z

modules/ROOT/pages/functions/temporal/format.adoc

+|===
+| Most characters yield a different output when they are repeated.
+| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value.
+| For details, refer to the documentation of the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter].


Do we need this link twice?

Usually, the Considerations points come just after the Description table, and I think just having the link in the Considerations table suffices.

modules/ROOT/pages/functions/temporal/format.adoc

JPryce-Aklundh · 2025-09-10T07:56:32Z

modules/ROOT/pages/functions/temporal/format.adoc

+
+|===
+
+Note how the days cannot be converted to hours and do not affect the query result.


Im not sure I follow here? Can you add a short explanation?

that was gibberish indeed - the example did not match at all what i wanted to point out. updated 👍

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

JoelBergstrand

Great!

JPryce-Aklundh

Good stuff! I have a few more suggestions.

Also, format() needs to be added to its own table on the Functions overview page:
https://neo4j.com/docs/cypher-manual/25/functions/
In that table, please add the labels, label:new[Introduced in Neo4j 2025.09] label:cypher[Cypher 25 only]

modules/ROOT/pages/functions/temporal/format.adoc

JPryce-Aklundh · 2025-09-11T06:41:09Z

modules/ROOT/pages/functions/temporal/format.adoc

+|===
+
+[[query-functions-temporal-format-instance-types]]
+== Instance types


Instance types and duration types being H2 (==) might become confusing navigation wise if more format functions are introduced (usually the functions themselves are on the H2 level).

I'll leave it up to you change for now or not (and so long as there is only 1, I think its fine to leave as is), but just thought I'd point it out :)

i'd say let's leave it for now, but definitely address it when we add more.
heading levels shouldn't interfere with anchored links either, so this sort of refactoring ought to be safe

gem-neo4j · 2025-09-11T07:03:04Z

modules/ROOT/pages/functions/temporal/format.adoc

+|===
+
+| instanceString
+| "322th day of the year, 3rd day of the week"


I know it is just an example, but it bothers me that we don't say 322nd 😅

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

modules/ROOT/pages/functions/index.adoc

modules/ROOT/pages/functions/temporal/format.adoc

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

JPryce-Aklundh

🎉

modules/ROOT/pages/functions/temporal/format.adoc

modules/ROOT/pages/values-and-types/temporal.adoc

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

modules/ROOT/pages/functions/temporal/format.adoc

modules/ROOT/pages/values-and-types/temporal.adoc

neo4j-docops-agent · 2025-09-16T07:21:06Z

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.

rsill-neo4j added 6 commits August 27, 2025 19:15

WiP format function

2d4b1c3

general structure, additions page entry, references

03a8731

examples for instance types

efeca11

added a block title

b594c52

examples for duration types

81a5bf5

clarification for duration conversions

b9ad57a

rsill-neo4j requested review from JPryce-Aklundh and JoelBergstrand August 29, 2025 07:52

JoelBergstrand self-assigned this Aug 29, 2025

rsill-neo4j and others added 6 commits September 2, 2025 13:56

nicer considerations block

2cbca9a

nicer character table for durations

f1f9c6c

Merge branch 'dev' into document-format-function

17cc934

reduced number of examples, reduced 'considerations' list, moved char…

b760987

…acters tables, added more headings

Merge branch 'dev' into document-format-function

64a517c

improved examples

935e5a7

JoelBergstrand requested changes Sep 4, 2025

View reviewed changes

rsill-neo4j added 2 commits September 4, 2025 16:46

review suggestions

aa5a14c

review suggestion

dff9453

JoelBergstrand assigned gem-neo4j Sep 8, 2025

gem-neo4j reviewed Sep 8, 2025

View reviewed changes

rsill-neo4j and others added 2 commits September 8, 2025 14:02

Update modules/ROOT/pages/functions/temporal/format.adoc

93e85bc

Co-authored-by: Gem Lamont <[email protected]>

review suggestions

7b99147

JPryce-Aklundh reviewed Sep 10, 2025

View reviewed changes

rsill-neo4j and others added 5 commits September 10, 2025 10:45

Apply suggestions from code review

ef697e4

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

review suggestions

b7d6eb2

Merge branch 'dev' into document-format-function

a8085ce

replaced the additions page example query

bb499cd

syntax fix

34579f2

JoelBergstrand approved these changes Sep 10, 2025

View reviewed changes

JPryce-Aklundh reviewed Sep 11, 2025

View reviewed changes

gem-neo4j reviewed Sep 11, 2025

View reviewed changes

rsill-neo4j and others added 2 commits September 11, 2025 09:47

Apply suggestions from code review

118abe6

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

review suggestions

e4bc6f8

JPryce-Aklundh reviewed Sep 11, 2025

View reviewed changes

modules/ROOT/pages/functions/index.adoc Outdated Show resolved Hide resolved

modules/ROOT/pages/functions/temporal/format.adoc Show resolved Hide resolved

rsill-neo4j and others added 2 commits September 11, 2025 11:32

removed labels from a test section

e9b8b32

Apply suggestions from code review

66ea4d7

Co-authored-by: Jens Pryce-Åklundh <[email protected]>

JPryce-Aklundh approved these changes Sep 11, 2025

View reviewed changes

rsill-neo4j added 2025.09 Cypher 25 labels Sep 11, 2025

rsill-neo4j commented Sep 11, 2025

View reviewed changes

rsill-neo4j and others added 2 commits September 12, 2025 10:16

EU <-> US examples

2d9bea5

added cheat sheet tags

eda89a5

rsill-neo4j commented Sep 12, 2025

View reviewed changes

modules/ROOT/pages/functions/temporal/format.adoc Outdated Show resolved Hide resolved

rsill-neo4j commented Sep 12, 2025

View reviewed changes

modules/ROOT/pages/values-and-types/temporal.adoc Outdated Show resolved Hide resolved

rsill-neo4j added 2 commits September 12, 2025 17:10

Apply suggestions from code review

4abf925

Merge branch 'dev' into document-format-function

8389c85

rsill-neo4j merged commit 90f1992 into dev Sep 16, 2025
4 checks passed

JPryce-Aklundh deleted the document-format-function branch September 17, 2025 09:04



		[[query-functions-temporal-format-duration-types-characters]]
		=== String pattern characters


		\|===

		Note how the days cannot be converted to hours and do not affect the query result.

Document format function #1374

Document format function #1374

Uh oh!

Conversation

rsill-neo4j commented Aug 29, 2025

Uh oh!

JoelBergstrand left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JPryce-Aklundh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoelBergstrand left a comment

Choose a reason for hiding this comment

Uh oh!

JPryce-Aklundh left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JPryce-Aklundh Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JPryce-Aklundh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

neo4j-docops-agent commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

JPryce-Aklundh left a comment •

edited

Loading

JPryce-Aklundh Sep 11, 2025 •

edited

Loading

neo4j-docops-agent commented Sep 16, 2025 •

edited

Loading